Sample Configuration
#####
## Constellation configuration file example
## ----------------------------------------
## Every option listed here can also be specified on the command line, e.g.
## `constellation-node --url=http://www.foo.com --port 9001 ...`
## (lists are given using comma-separated strings)
## If both command line parameters and a configuration file are given, the
## command line options will take precedence.
##
## The only strictly necessary option is `port`, however it's recommended to
## set at least the following:
##
## --url The URL to advertise to other nodes (reachable by them)
## --port The local port to listen on
## --workdir The folder to put stuff in (default: .)
## --socket IPC socket to create for access to the Private API
## --othernodes "Boot nodes" to connect to to discover the network
## --publickeys Public keys hosted by this node
## --privatekeys Private keys hosted by this node (in corresponding order)
##
## Example usage:
##
## constellation-node --workdir=data --generatekeys=foo
## (To generate a keypair foo in the data directory)
##
## constellation-node --url=https://localhost:9000/ \
## --port=9000 \
## --workdir=data \
## --socket=constellation.ipc \
## --othernodes=https://localhost:9001/ \
## --publickeys=foo.pub \
## --privatekeys=foo.key
##
## constellation-node sample.conf
##
## constellation-node --port=9002 sample.conf
## (This overrides the port value given in sample.conf)
##
## Note on defaults: "Default:" below indicates the value that will be assumed
## if the option is not present either in the configuration file or as a command
## line parameter.
##
## Note about security: In the default configuration, Constellation will
## automatically generate TLS certificates and trust other nodes' certificates
## when they're first encountered (trust-on-first-use). See the documentation
## for tlsservertrust and tlsclienttrust below. To disable TLS entirely, e.g.
## when using Constellation in conjunction with a VPN like WireGuard, set tls to
## off.
#####
## Externally accessible URL for this node's public API (this is what's
## advertised to other nodes on the network, and must be reachable by them.)
url = "http://127.0.0.1:9001/"
## Port to listen on for the public API.
port = 9001
## Directory in which to put and look for other files referenced here.
##
## Default: The current directory
workdir = "data"
## Socket file to use for the private API / IPC. If this is commented out,
## the private API will not be accessible.
##
## Default: Not set
socket = "constellation.ipc"
## Initial (not necessarily complete) list of other nodes in the network.
## Constellation will automatically connect to other nodes not in this list
## that are advertised by the nodes below, thus these can be considered the
## "boot nodes."
##
## Default: []
othernodes = ["http://127.0.0.1:9000/"]
## The set of public keys this node will host.
##
## Default: []
publickeys = ["foo.pub"]
## The corresponding set of private keys. These must correspond to the public
## keys listed above.
##
## Default: []
privatekeys = ["foo.key"]
## Optional comma-separated list of paths to public keys to add as recipients
## for every transaction sent through this node, e.g. for backup purposes.
## These keys must be advertised by some Constellation node on the network, i.e.
## be in a node's publickeys/privatekeys lists.
##
## Default: []
alwayssendto = []
## Optional file containing the passwords needed to unlock the given privatekeys
## (the file should contain one password per line -- add an empty line if any
## one key isn't locked.)
##
## Default: Not set
# passwords = "passwords"
## Storage engine used to save payloads and related information. Options:
## - bdb:path (BerkeleyDB)
## - dir:path (Directory/file storage - can be used with e.g. FUSE-mounted
## file systems.)
## - leveldb:path (LevelDB - experimental)
## - memory (Contents are cleared when Constellation exits)
## - sqlite:path (SQLite - experimental)
##
## Default: "dir:storage"
storage = "dir:storage"
## Verbosity level (each level includes all prior levels)
## - 0: Only fatal errors
## - 1: Warnings
## - 2: Informational messages
## - 3: Debug messages
##
## At the command line this can be specified using -v0, -v1, -v2, -v3, or
## -v (2) and -vv (3).
##
## Default: 1
verbosity = 1
## Optional IP whitelist for the public API. If unspecified/empty,
## connections from all sources will be allowed (but the private API remains
## accessible only via the IPC socket above.) To allow connections from
## localhost when a whitelist is defined, e.g. when running multiple
## Constellation nodes on the same machine, add "127.0.0.1" and "::1" to
## this list.
##
## Default: Not set
# ipwhitelist = ["10.0.0.1", "2001:0db8:85a3:0000:0000:8a2e:0370:7334"]
## TLS status. Options:
##
## - strict: All connections to and from this node must use TLS with mutual
## authentication. See the documentation for tlsservertrust and
## tlsclienttrust below.
## - off: Mutually authenticated TLS is not used for in- and outbound
## connections, although unauthenticated connections to HTTPS hosts are
## still possible. This should only be used if another transport security
## mechanism like WireGuard is in place.
##
## Default: "strict"
tls = "strict"
## Path to a file containing the server's TLS certificate in Apache format.
## This is used to identify this node to other nodes in the network when they
## connect to the public API.
##
## This file will be auto-generated if it doesn't exist.
##
## Default: "tls-server-cert.pem"
tlsservercert = "tls-server-cert.pem"
## List of files that constitute the CA trust chain for the server certificate.
## This can be empty for auto-generated/non-PKI-based certificates.
##
## Default: []
tlsserverchain = []
## The private key file for the server TLS certificate.
##
## This file will be auto-generated if it doesn't exist.
##
## Default: "tls-server-key.pem"
tlsserverkey = "tls-server-key.pem"
## TLS trust mode for the server. This decides who's allowed to connect to it.
## Options:
##
## - whitelist: Only nodes that have previously connected to this node and
## been added to the tlsknownclients file below will be allowed to connect.
## This mode will not add any new clients to the tlsknownclients file.
##
## - tofu: (Trust-on-first-use) Only the first node that connects identifying
## as a certain host will be allowed to connect as the same host in the
## future. Note that nodes identifying as other hosts will still be able
## to connect -- switch to whitelist after populating the tlsknownclients
## list to restrict access.
##
## - ca: Only nodes with a valid certificate and chain of trust to one of
## the system root certificates will be allowed to connect. The folder
## containing trusted root certificates can be overriden with the
## SYSTEM_CERTIFICATE_PATH environment variable.
##
## - ca-or-tofu: A combination of ca and tofu: If a certificate is valid,
## it is always allowed and added to the tlsknownclients list. If it is
## self-signed, it will be allowed only if it's the first certificate this
## node has seen for that host.
##
## - insecure-no-validation: Any client can connect, however they will still
## be added to the tlsknownclients file.
##
## Default: "tofu"
tlsservertrust = "tofu"
## TLS known clients file for the server. This contains the fingerprints of
## public keys of other nodes that are allowed to connect to this one.
##
## Default: "tls-known-clients"
tlsknownclients = "tls-known-clients"
## Path to a file containing the client's TLS certificate in Apache format.
## This is used to identify this node to other nodes in the network when it is
## connecting to their public APIs.
##
## This file will be auto-generated if it doesn't exist.
##
## Default: "tls-client-cert.pem"
tlsclientcert = "tls-client-cert.pem"
## List of files that constitute the CA trust chain for the client certificate.
## This can be empty for auto-generated/non-PKI-based certificates.
##
## Default: []
tlsclientchain = []
## The private key file for the client TLS certificate.
##
## This file will be auto-generated if it doesn't exist.
##
## Default: "tls-client-key.pem"
tlsclientkey = "tls-client-key.pem"
## TLS trust mode for the client. This decides which servers it will connect to.
## Options:
##
## - whitelist: This node will only connect to servers it has previously seen
## and added to the tlsknownclients file below. This mode will not add
## any new servers to the tlsknownservers file.
##
## - tofu: (Trust-on-first-use) This node will only connect to the same
## server for any given host. (Similar to how OpenSSH works.)
##
## - ca: The node will only connect to servers with a valid certificate and
## chain of trust to one of the system root certificates. The folder
## containing trusted root certificates can be overriden with the
## SYSTEM_CERTIFICATE_PATH environment variable.
##
## - ca-or-tofu: A combination of ca and tofu: If a certificate is valid,
## it is always allowed and added to the tlsknownservers list. If it is
## self-signed, it will be allowed only if it's the first certificate this
## node has seen for that host.
##
## - insecure-no-validation: This node will connect to any server, regardless
## of certificate, however it will still be added to the tlsknownservers
## file.
##
## Default: "ca-or-tofu"
tlsclienttrust = "ca-or-tofu"
## TLS known servers file for the client. This contains the fingerprints of
## public keys of other nodes that this node has encountered.
##
## Default: "tls-known-servers"
tlsknownservers = "tls-known-servers"